home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / games / nhak_src.zip / INSTALL.OVL < prev    next >
Text File  |  1993-03-16  |  15KB  |  294 lines
  1.         Instructions for compiling and installing the Overlaid
  2.             NetHack 3.0 on an MS-DOS system
  3.         ======================================================
  4.             (or, How to make PC NetHack 3.0)
  5.               Last revision: June 02, 1990
  6.  
  7.     (Credit for a runnable full PC NetHack 3.0 goes to the overlay team of
  8.      Pierre Martineau, Stephen Spackman, Norm Meluch, and Kevin Smolkowski,
  9.      who built on the work of Steve Creps and Mike Threepoint.)
  10.  
  11.  
  12. I.  Dispelling the Myths:
  13.  
  14.     Compiling NetHack is not as easy as it sounds, nor as hard as it looks,
  15.     however it will behoove you to read this entire file through before
  16.     beginning the task.
  17.  
  18.     The NetHack executable that you are about to get will be generated by an
  19.     overlay linker.  The beauty of this overlay linker beastie is that it will
  20.     create an executable that will function in much less memory than it would
  21.     "normally" take to run.  Do not be deceived.  The RAM requirement for the
  22.     overlay version is about 550k!  You can load the program in less RAM, but
  23.     you will begin to experience a serious amount of disk thrashing at 530k
  24.     or less.  Absolute minimum will probably be in the neighborhood of 380-400k.
  25.     You do not want to run the program like that!  The more free RAM you have
  26.     available for the program, the more smoothly it will run.
  27.  
  28.     The magic piece to the overlay puzzle is a program called ovlmgr.asm.  This
  29.     is a replacement for the Microsoft (and we use the term loosely) overlay
  30.     manager.  This program has been enhanced since its release in November
  31.     1989.  It will now allow NetHack to use EMS memory if any is available,
  32.     therefore, RAM requirements can be reduced to the minimum with at least
  33.     256K of EMS.
  34.  
  35.     As of patch level 7, version 3.0 has an added feature in the Makefile.  
  36.     This feature enables a structured break-up of the object modules so that 
  37.     we can link heavily used functions together without actual source code
  38.     movement.  This has provided a great speed improvement for this release.
  39.     See the file others\maintain.ovl for more information on this structuring.
  40.  
  41.  
  42. II.  How long is this going to take?
  43.  
  44.     On an XT class PC it has been rumored that NetHack can be built in 8 - 10
  45.       hours.
  46.     On a 286 10MHz PC you can build NetHack in about 3 - 3.5 hours,
  47.     On the flip side if you have a 386 33MHz PC with a *VERRRRY* fast hard
  48.       disk, math coprocessor, 32 bit bus, and severe I/O caching you will have
  49.       NetHack in about 15 minutes!
  50.     
  51.     Hope you enjoy the game.  We have worked very hard to try to bring it back
  52.     to the PC.
  53.  
  54.  
  55. III.  Tools:
  56.  
  57.    The following programs are necessary to successfully compile the overlaid
  58.    version of NetHack:
  59.  
  60.    A.    Microsoft C, version 5.1 or newer.
  61.  
  62.    B.    The Microsoft Overlay Linker, version 3.6 or newer or preferably,
  63.      the Microsoft Segmented Linker, version 5.01.20 or newer. The
  64.      overlay linker has been known to cause problems with other
  65.      programs, but not with NetHack, yet.
  66.     One of these linkers should be included in your MSC version.
  67.  
  68.    C.    NDmake, version 4.5 or newer, (available from your local ftp site).
  69.      As the overlay makefile is pretty large, you will want to use the
  70.      large model of NDmake: MAKE45L.EXE, as your make program.
  71.     MSC 6.0 has a new make program distributed with it that might be
  72.      able to handle the Makefile.ovl with a few modifications.  This has
  73.      not been completely tested.  We recommend NDmake 4.5.
  74.  
  75.  
  76. IV.  Optional tools:
  77.  
  78.    The following programs are not necessary, because pre-built copies of the
  79.    files are included in this distribution.  However, if you want to build
  80.    NetHack 100% from scratch, you will need them.
  81.  
  82.    A.    An 80x86 assembler.
  83.     This is for assembling the ovlmgr.asm file into ovlmgr.obj.  If you
  84.      want to assemble your own copy of the overlay manager.  The file
  85.      others\ovlmgr.uu is a uuencoded version of the assembled ovlmgr.asm.
  86.     For details, see the file ovlmgr.doc.
  87.  
  88.    B.    Yacc/Bison & Lex/Flex workalike programs for the PC.
  89.     The source files for the special levels compiler are built using
  90.      bison and flex.  Precompiled copies of the files lev_lex.c, and
  91.      lev_comp.c have been provided if you do not have these utilities.
  92.     Bison & flex should also be available at your local ftp site.
  93.  
  94.  
  95. V.  To compile your copy of NetHack on a MSDOS machine:
  96.     (or "just follow the "simple" steps outlined below.)
  97.  
  98. 1.  It almost goes without saying that you should make sure that your tools
  99.     are set up and running correctly.
  100.  
  101. 2.  Make sure all the NetHack files are in the appropriate directory
  102.     structure.  You should have a main directory with subdirectories
  103.     src, include, auxil, others, amiga, mac, and vms.  If you do not
  104.     follow this structure, the Makefile.ovl will not function properly.
  105.  
  106.     All the shared and UNIX-specific .c files and the source Makefile(.src)
  107.     belong in src; all the PC *.c files and PC make files belong in others;
  108.     all the .h files belong in include; other assorted files belong in auxil.
  109.     Check the file "Files" in your top level directory for an exact listing
  110.     of what file is in which directory.
  111.  
  112.     We will not need any of the files from the amiga, mac, and vms
  113.     directories, so you can delete them if you need the space.
  114.  
  115.     If you downloaded or ftp'd the sources from a UNIX system, the lines
  116.     will probably end in UNIX-style newlines, instead of the carriage
  117.     return and line feed pairs used by DOS.  Some programs have trouble
  118.     with them,  you may need to convert them (with a utility like
  119.     Rahul Dhesi's "flip").  Also, every file should end with an empty
  120.     line, because both Microsoft C and MASM have a habit of ignoring the
  121.     last line of each file. 
  122.  
  123. 3.  Move/Copy files from the others directory to your src directory
  124.     based on the following criteria.  You will probably want to include
  125.     most all of these files.
  126.  
  127.     You will definitely need pc*.c, msdos.c, and trampoli.c.
  128.  
  129.     random.c is only needed if you want the high-quality random number
  130.     generation routines.
  131.  
  132.     You should be able to use either others/lev_lex.c (generated by flex)
  133.     or src/lev_lex.c (generated by lex), but the one in src is smaller.
  134.     If you have flex or some other lex work-alike, you can use that to
  135.     produce lev_lex.c from lev_comp.l.
  136.  
  137.     The file termcap.uu is the fixed version of the Fred Fish termcap library.
  138.     You will need to run a uudecode utility on it to generate the file
  139.     termcap.arc.  termcap.arc contains several files of termcap routines.
  140.     Using them with NetHack involves very little knowledge of the UNIX concept
  141.     of a termcap database; mostly you need to know enough to set a TERM
  142.     environment variable.  You can unarc termcap.arc here in the others
  143.     directory, but if you are going to use it, it is probably best to unarc a
  144.     copy in the src directory.  That way you will not miss copying any
  145.     files over.  Wherever you unarc it, get rid of the included makefile
  146.     since a better version has been provided as Makefile.lib.
  147.  
  148.     ovlmgr.uu (MS-DOS overlay manager) is the uuencoded assembled
  149.     object module for the overlay manager in case you do not have an assembler.
  150.     You will need to run a uudecode utility on this file too, to generate
  151.     ovlmgr.obj.
  152.  
  153.     Exesmurf.uu is the uuencoded copy of the exesmurf utility which displays
  154.     and modifies the contents of an executable file header.  It is similar
  155.     to Microsoft's exemod utility but it provides infomation on overlays
  156.     which EXEMOD does not.  It is used to modify the Nethack executable's
  157.     memory allocation.
  158.  
  159. 4.  Rename the file Makefile.ovl to "Makefile." (no extension), and move 
  160.     it into your src directory.
  161.  
  162.     The PC NetHack makefiles are set up for NDMAKE, a public domain
  163.     "make" utility.  Both Microsoft's "make" leaves much to
  164.     be desired.  It is worth the extra effort to get NDMAKE if you don't
  165.     already have it.  Among other things, NDMAKE automatically generates
  166.     link response files when the link command involves so many objects
  167.     that the command would become longer than DOS can handle.  If you must
  168.     use Microsoft's or Borland's "make", you'll need to edit the makefile
  169.     into a form your make can use, and add instructions to generate a link
  170.     response file.
  171.  
  172.     If you are going to be constructing the Fred Fish termlib you will need 
  173.     the Makefile.lib.  Copy this to your source directory too, and do not 
  174.     change its name.
  175.  
  176.     Makefile.top in the top directory, Makefile.src in the src directory,
  177.     and Makefile.aux(il) in the auxil directory are for UNIX NetHack. You
  178.     will not need these, and you may delete them.
  179.  
  180.     Makefile.pc, Makefile.msc, and Makefile.tos are for compiling non-
  181.     overlaid versions of NetHack, and for the atari.  You may delete these
  182.     too.
  183.  
  184. 4.  Now go to the include subdirectory to edit a couple of the header files
  185.     there.
  186.  
  187.     First edit config.h according to the comments to match your system and
  188.     desired set of features.  Mostly you need to check the WIZARD option,
  189.     make sure the HACKDIR is set properly, and check TERMLIB and COMPRESS.
  190.   
  191.     Using Microsoft C and overlays, we've managed to enable all the special
  192.     features.  You may include all the neat features you want.
  193.  
  194.     Also check pcconf.h, which should not need much editing (if you are
  195.     including termcap.uu and random.c).  If you are not including these, you
  196.     will need to comment out TERMLIB and/or RANDOM.  You should make doubly
  197.     certain that OVERLAY is defined in pcconf.h, since otherwise things will
  198.     compile properly but very ugly things are likely to happen wherever
  199.     function pointers cross overlay boundaries - the linker is a little thick
  200.     about that.
  201.  
  202.     Commenting out the #define TERMLIB in pcconf.h to disable use of termcap
  203.     routines (relying on the ANSI_DEFAULT feature) will make your job a bit
  204.     easier.  However, you can compile with both TERMLIB and ANSI_DEFAULT
  205.     and simply not set your TERM variable if you do not wish to use the
  206.     termcap file settings.
  207.  
  208. 6.  If you want to change the high score list behavior, examine the top of
  209.     topten.c, in the src directory.  You may want to change the definitions of
  210.     PERSMAX, POINTSMIN, and ENTRYMAX.  I set POINTSMIN to 51 and ENTRYMAX to
  211.     50 to keep the size of the score list down.
  212.  
  213. 7.  Go to the src directory and edit the top of your Makefile.  Be sure the
  214.     directory you want the game installed (GAMEDIR) in actually exists.
  215.  
  216.     If you elected not to use the high-quality BSD random number routines by
  217.     commenting out RANDOM in pcconf.h or tosconf.h, comment out (or set equal
  218.     to nothing) the RANDOM macro in your Makefile.
  219.  
  220.     If you elected to use Fred Fish's termcap library (bundled in as
  221.     termcap.arc), you will have to generate termlib.lib from those sources
  222.     by typing "make -f makefile.lib".  You must also set the TERMLIB option
  223.     in Makefile.ovl to link in the resulting termlib.lib.
  224.  
  225.     If you have a MASM compatible Assembler, you may want to enable the option
  226.     in the makefile to rebuild ovlmgr.obj, although a ready-made object file 
  227.     is provided for those of you without.   Before assembling ovlmgr, be sure
  228.     to read ovlmgr.doc as there are several options that you may or may not
  229.     wish to enable/disable.
  230.     
  231.     If you are recompiling after patching your sources, or if you got your
  232.     files from somewhere other than the official distribution, "touch
  233.     makedefs.c" to ensure that certain files (onames.h and pm.h) are remade,
  234.     lest potentially troublesome timestamps fool "make".
  235.  
  236. 8.  Now, enter "make45l install", and take a long siesta; your computer will
  237.     be occupied for a long time.  If all goes well, you will get an executable.
  238.  
  239. 9.  Make sure the support files -- data, rumors, cmdhelp, opthelp, help, hh,
  240.     history, license, and oracles (if ORACLE was #define'd) -- were copied
  241.     to the game directory.  If not, move them there from the auxil directory
  242.     yourself.  rumors can be created manually by entering "makedefs -r",
  243.     data by entering "makedefs -d".
  244.  
  245.     If you compiled in the special levels (if STRONGHOLD was #define'd), make
  246.     sure castle, tower?, and possibly endgame are there, too.  They can be
  247.     created manually by entering "lev_comp filename.des", where filename.des
  248.     is the appropriate description file (found in the auxil directory).
  249.  
  250.     Make sure the files NetHack.cnf and termcap also made it to your game
  251.     directory.  If not go to the others directory and copy NetHack.cnf and
  252.     termcap to your game directory.  Edit NetHack.cnf to reflect your
  253.     particular setup and personal preferences, by following the comments.
  254.  
  255.     If you'll be running NetHack from a different subdirectory, you will
  256.     want to "set HACKDIR=c:\games\nethack" (or whatever drive and directory 
  257.     you want to use) now.  Add it to your autoexec.bat (in DOS), if you'll 
  258.     be playing often.
  259.  
  260. 11. Play NetHack.  If it works, you're done!
  261.  
  262.  
  263. Notes
  264. -----
  265. 1)  First and foremost:  We have been developing with MSC 5.1 as a compiler
  266.     and NDmake 4.5 as a make.  NDmake is readily available on the Usenet;
  267.     obtaining MSC might be more of a problem.  MSC 5.0 is broken.  You *will
  268.     not* be able to compile the overlay version with that compiler due to
  269.     problems with the /Gt option allowing the CONST segment to become
  270.     > 64k when linking.
  271.     MSC 6.0 and its make utility have been used to generate an overlaid
  272.     NetHack.exe, however sufficient testing has not been completed at this
  273.     time for us to "recommend" its use.
  274.  
  275. 2)  Save files and bones files from previous versions will not work with
  276.     NetHack 3.0.  Don't bother trying to keep them.  Record (score) files
  277.     from before 3.0 patchlevel 7 will almost work, but you need to make one
  278.     change manually to them:  At the end of each line is a word or phrase
  279.     specifying what killed the player.  Change the string to start with the
  280.     words "killed by", "killed by a", or "killed by an" (whichever is
  281.     appropriate).  If the death was petrification, it should read "petrified
  282.     by" instead of "killed by".  Don't change "starvation", "quit", "escaped",
  283.     or "ascended".
  284.  
  285. 3)  To install an update of NetHack after changing something, enter "make"
  286.     from the src directory.  If you add, delete, or reorder monsters or
  287.     objects, or you change the format of saved level files, delete any save
  288.     and bones files.  (Trying to use such files sometimes produces amusing
  289.     confusions on the game's part, but usually crashes.)
  290.  
  291. 4)  During linking the Microsoft Overlay Linker will need temporary storage
  292.     space.  Make sure you have about a meg of free disk wherever you have
  293.     defined your temporary storage.
  294.